<!doctype html>


<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>html (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>





<div class="colmask rightmenu">
<div class="colleft">
    <div class="col1">
      <!-- Column 1 start -->

<div id="title">
       <span class="fn">html</span>
</div>

<hr/>


  <h2>Classes</h2>
 <div class="fn-constructor">
        <a href="class_goog_html_SafeHtml.html">
          goog.html.SafeHtml</a><br/>
        <div class="class-details">A string that is safe to use in HTML context in DOM APIs and HTML documents.

A SafeHtml is a string-like object that carries the security type contract
that its value as a string will not cause untrusted script execution when
evaluated as HTML in a browser.

Values of this type are guaranteed to be safe to use in HTML contexts,
such as, assignment to the innerHTML DOM property, or interpolation into
a HTML template in HTML PC_DATA context, in the sense that the use will not
result in a Cross-Site-Scripting vulnerability.

Instances of this type must be created via the factory methods
(<code> goog.html.SafeHtml.from</code>, <code> goog.html.SafeHtml.htmlEscape</code>), etc
and not by invoking its constructor.  The constructor intentionally takes no
parameters and the type is immutable; hence only a default instance
corresponding to the empty string can be obtained via constructor invocation.

</div>
 </div>
 <div class="fn-constructor">
        <a href="class_goog_html_SafeStyle.html">
          goog.html.SafeStyle</a><br/>
        <div class="class-details">A string-like object which represents a sequence of CSS declarations
(<code> propertyName1: propertyvalue1; propertyName2: propertyValue2; ...</code>)
and that carries the security type contract that its value, as a string,
will not cause untrusted script execution (XSS) when evaluated as CSS in a
browser.

Instances of this type must be created via the factory method,
(<code> goog.html.SafeStyle.fromConstant</code>), and not by invoking its
constructor. The constructor intentionally takes no parameters and the type
is immutable; hence only a default instance corresponding to the empty
string can be obtained via constructor invocation.

A SafeStyle's string representation (<code> #getSafeStyleString()</code>) can
safely:
<ul><li>Be interpolated as the entire content of a *quoted* HTML style
      attribute, or before already existing properties. The SafeStyle string
      *must be HTML-attribute-escaped* (where " and ' are escaped) before
      interpolation.
  <li>Be interpolated as the entire content of a {}-wrapped block within a
      stylesheet, or before already existing properties. The SafeStyle string
      should not be escaped before interpolation. SafeStyle's contract also
      guarantees that the string will not be able to introduce new properties
      or elide existing ones.
  <li>Be assigned to the style property of a DOM node. The SafeStyle string
      should not be escaped before being assigned to the property.
</li></li></li></ul>

A SafeStyle may never contain literal angle brackets. Otherwise, it could
be unsafe to place a SafeStyle into a &lt;style&gt; tag (where it can't
be HTML escaped). For example, if the SafeStyle containing
"<code> font: 'foo &amp;lt;style/&amp;gt;&amp;lt;script&amp;gt;evil&amp;lt;/script&amp;gt;'</code>" were
interpolated within a &lt;style&gt; tag, this would then break out of the
style context into HTML.

A SafeStyle may contain literal single or double quotes, and as such the
entire style string must be escaped when used in a style attribute (if
this were not the case, the string could contain a matching quote that
would escape from the style attribute).

Values of this type must be composable, i.e. for any two values
<code> style1</code> and <code> style2</code> of this type,
<code> style1.getSafeStyleString() + style2.getSafeStyleString()</code> must
itself be a value that satisfies the SafeStyle type constraint. This
requirement implies that for any value <code> style</code> of this type,
<code> style.getSafeStyleString()</code> must not end in a "property value" or
"property name" context. For example, a value of <code> background:url("</code>
or <code> font-</code> would not satisfy the SafeStyle contract. This is because
concatenating such strings with a second value that itself does not contain
unsafe CSS can result in an overall string that does. For example, if
<code> javascript:evil())"</code> is appended to <code> background:url("</code>, the
resulting string may result in the execution of a malicious script.

TODO(user): Consider whether we should implement UTF-8 interchange
validity checks and blacklisting of newlines (including Unicode ones) and
other whitespace characters (\t, \f). Document here if so and also update
SafeStyle.fromConstant().

The following example values comply with this type's contract:
<ul><li><pre class="lang-js prettyprint">width: 1em;</pre><li><pre class="lang-js prettyprint">height:1em;</pre><li><pre class="lang-js prettyprint">width: 1em;height: 1em;</pre><li><pre class="lang-js prettyprint">background:url('<a href="http://url">http://url</a>');</pre></li></li></li></li></ul>
In addition, the empty string is safe for use in a CSS attribute.

The following example values do NOT comply with this type's contract:
<ul><li><pre class="lang-js prettyprint">background: red</pre> (missing a trailing semi-colon)
  <li><pre class="lang-js prettyprint">background:</pre> (missing a value and a trailing semi-colon)
  <li><pre class="lang-js prettyprint">1em</pre> (missing an attribute name, which provides context for
      the value)
</li></li></li></ul></div>
 </div>
 <div class="fn-constructor">
        <a href="class_goog_html_SafeUrl.html">
          goog.html.SafeUrl</a><br/>
        <div class="class-details">A string that is safe to use in URL context in DOM APIs and HTML documents.

A SafeUrl is a string-like object that carries the security type contract
that its value as a string will not cause untrusted script execution
when evaluated as a hyperlink URL in a browser.

Values of this type are guaranteed to be safe to use in URL/hyperlink
contexts, such as, assignment to URL-valued DOM properties, or
interpolation into a HTML template in URL context (e.g., inside a href
attribute), in the sense that the use will not result in a
Cross-Site-Scripting vulnerability.

Note that, as documented in <code> goog.html.SafeUrl.unwrap</code>, this type's
contract does not guarantee that instances are safe to interpolate into HTML
without appropriate escaping.

Note also that this type's contract does not imply any guarantees regarding
the resource the URL refers to.  In particular, SafeUrls are <b>not</b>
safe to use in a context where the referred-to resource is interpreted as
trusted code, e.g., as the src of a script tag.

Instances of this type must be created via the factory methods
(<code> goog.html.SafeUrl.from</code>, <code> goog.html.SafeUrl.sanitize</code>), etc and
not by invoking its constructor.  The constructor intentionally takes no
parameters and the type is immutable; hence only a default instance
corresponding to the empty string can be obtained via constructor invocation.

</div>
 </div>
 <div class="fn-constructor">
        <a href="class_goog_html_TrustedResourceUrl.html">
          goog.html.TrustedResourceUrl</a><br/>
        <div class="class-details">A URL which is under application control and from which script, CSS, and
other resources that represent executable code, can be fetched.

Given that the URL can only be constructed from strings under application
control and is used to load resources, bugs resulting in a malformed URL
should not have a security impact and are likely to be easily detectable
during testing. Given the wide number of non-RFC compliant URLs in use,
stricter validation could prevent some applications from being able to use
this type.

Instances of this type must be created via the factory method,
(<code> goog.html.TrustedResourceUrl.fromConstant</code>), and not by invoking its
constructor. The constructor intentionally takes no parameters and the type
is immutable; hence only a default instance corresponding to the empty
string can be obtained via constructor invocation.

</div>
 </div>
   
<br/>

  <div class="legend">
        <span class="key publickey"></span><span>Public</span>
        <span class="key protectedkey"></span><span>Protected</span>
        <span class="key privatekey"></span><span>Private</span>
  </div>









<div class="section">
  <table class="horiz-rule">


  </table>
</div>







  <h2>Global Properties</h2>





<div class="section">
  <table class="horiz-rule">


     <tr class="even entry private">
       <td class="access"></td>





  <a name="goog.html.SAFE_URL_PATTERN_"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">SAFE_URL_PATTERN_</span>
        : 
     </div>


     <div class="entryOverview">
       A pattern that recognizes a commonly useful subset of URLs that satisfy
the SafeUrl contract.

This regular expression matches a subset of URLs that will not cause script
execution if used in URL context within a HTML document. Specifically, this
regular expression matches if (comment from here on and regex copied from
Soy's EscapingConventions):
(1) Either a protocol in a whitelist (http, https, mailto).
(2) or no protocol.  A protocol must be followed by a colon. The below
    allows that by allowing colons only after one of the characters [/?#].
    A colon after a hash (#) must be in the fragment.
    Otherwise, a colon after a (?) must be in a query.
    Otherwise, a colon after a single solidus (/) must be in a path.
    Otherwise, a colon after a double solidus (//) must be in the authority
    (before port).

The pattern disallows &amp;, used in HTML entity declarations before
one of the characters in [/?#]. This disallows HTML entities used in the
protocol name, which should never happen, e.g. "http" for "http".
It also disallows HTML entities in the first path part of a relative path,
e.g. "foo&lt;bar/baz".  Our existing escaping functions should not produce
that. More importantly, it disallows masking of a colon,
e.g. "javascript:...".


     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl.js.source.html#line272">Code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>





  <a name="goog.html.ScrubberTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">ScrubberTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_labs_html_scrubber_test.js.source.html#line16">Code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>





  <a name="goog.html.UtilsTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">UtilsTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_utils_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>





  <a name="goog.html.legacyconversions"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">legacyconversions</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_legacyconversions.js.source.html#line82">Code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>





  <a name="goog.html.legacyconversionsTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">legacyconversionsTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_legacyconversions_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>





  <a name="goog.html.safeHtmlTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">safeHtmlTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safehtml_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>





  <a name="goog.html.safeStyleTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">safeStyleTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safestyle_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>





  <a name="goog.html.safeUrlTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">safeUrlTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>





  <a name="goog.html.testing"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">testing</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_testing.js.source.html#line27">Code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>





  <a name="goog.html.trustedResourceUrlTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">trustedResourceUrlTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_trustedresourceurl_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>





  <a name="goog.html.uncheckedconversions"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">uncheckedconversions</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_uncheckedconversions.js.source.html#line31">Code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>





  <a name="goog.html.uncheckedconversionsTest"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">uncheckedconversionsTest</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_uncheckedconversions_test.js.source.html#line19">Code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>





  <a name="goog.html.utils"></a>

  <td>


     <div class="arg">
        <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.</span><span class="entryName">utils</span>
        : 
     </div>


     <div class="entryOverview">
       <span class='nodesc'>No description.</span>
     </div>

  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_utils.js.source.html#line20">Code &raquo;</a>
  </td>
     </tr>


  </table>
</div>
      <!-- Column 1 end -->
    </div>

        <div class="col2">
          <!-- Column 2 start -->
          <div class="col2-c">
            <h2 id="ref-head">Package html</h2>
            <div id="localView"></div>
          </div>

          <div class="col2-c">
            <h2 id="ref-head">Package Reference</h2>
            <div id="sideTypeIndex" rootPath="" current="html"></div>
          </div>
          <!-- Column 2 end -->
        </div>
</div>
</div>

</body>
</html>
